---
title: Emoji extension
sidebar_label: Emojis
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Who loves emojis? Everyone loves emojis! This package provides support for rendering emoji, either
their unicode character, or with SVG/PNGs. It utilizes [Emojibase][emojibase] for accurate and
up-to-date data.

```tsx
<Interweave
	content="This will convert emoji unicode characters (🌀), shortcodes (:cyclone:), and emoticons to SVGs! :)"
	matchers={[
		new EmojiMatcher('emoji', {
			convertEmoticon: true,
			convertShortcode: true,
		}),
	]}
	emojiPath={getSvgPathForEmoji}
/>
```

## Requirements

- [Emojibase][emojibase]

## Installation

<Tabs
  groupId="package-manager"
  defaultValue="yarn"
  values={[
    { label: 'Yarn', value: 'yarn' },
    { label: 'NPM', value: 'npm' },
  ]}
>
  <TabItem value="yarn">

```bash
yarn add interweave interweave-emoji emojibase
```

  </TabItem>
  <TabItem value="npm">

```bash
npm install interweave interweave-emoji emojibase
```

  </TabItem>
</Tabs>

## Matching emojis

The `EmojiMatcher` makes use of complex regex patterns provided by Emojibase to find and replace
emoji unicode sequences with SVG/PNGS.

```tsx
import { Interweave } from 'interweave';
import { EmojiMatcher } from 'interweave-emoji';
```

```tsx
<Interweave content="Emoji unicode character: 🌀" matchers={[new EmojiMatcher('emoji')]} />
```

### Props

The following props are available for `<Emoji />` components, all of which should be passed to an
`<Interweave />` instance.

- `emojiSize` (`string | number`) - The width and height of emojis. Defaults to `1em`.
- `emojiLargeSize` (`string | number`) - The width and height of enlarged emojis. Defaults to `3em`.
- `emojiPath` (`string | func`) - A path to the [PNG or SVG file](#displaying-svgs-or-pngs).
- `enlargeEmoji` (`boolean`) - Whether to enlarge the emoji or not. Automatically triggers via the
  matcher but can be forced with this prop. Defaults to `false`.
- `renderUnicode` (`boolean`) - Render the unicode character instead of an image. Defaults to
  `false`.

### Result

Both unicode literal characters and escape sequences are supported when matching. If a match is
found, an `<Emoji />` component will be rendered and passed some of the following props.

- `emoticon` (`string`) - If applicable, an emoticon for the specific emoji character.
- `hexcode` (`string`) - The hexcode for the specific emoji character.
- `shortcode` (`string`) - The shortcode for the specific emoji character.
- `unicode` (`string`) - The unicode literal character.

## Loading emoji data

Before emoji can be rendered, emoji data must be loaded from a CDN. To do this, the `useEmojiData()`
hook can be used, which will fetch emoji data from Emojibase's CDN. The hook returns a tuple, with
the first item being an array of all emoji data, the second item being the source object (locale,
version, etc), and the third being the data manager instance.

```tsx
import BaseInterweave, { InterweaveProps } from 'interweave';
import { useEmojiData } from 'interweave-emoji';

export default function Interweave(props: InterweaveProps) {
	const [emojis, source, manager] = useEmojiData({ compact: false, shortcodes: ['emojibase'] });

	return <BaseInterweave {...props} emojiSource={source} />;
}
```

The hook supports the following optional options.

- `compact` (`boolean`) - Whether to load the compact or full dataset. Defaults to `false`.
- `locale` (`Locale`) - The localized data to fetch. Defaults to `en`.
  [View supported locales](https://emojibase.dev/docs/datasets#supported-locales).
- `shortcodes` (`string[]`) - List of shortcode presets to load and join with emojis. Defaults to
  `emojibase`. [View supported presets](https://emojibase.dev/docs/shortcodes).
- `throwErrors` (`boolean`) - Throw an error when the fetch fails. Defaults to `true`.
- `version` (`string`) - The `emojibase-data` release version to fetch. Defaults to `latest`.
  [Read more](https://emojibase.dev/docs/api#fetchfromcdn).

## Converting emoticons

Emoticons have been around longer than emoji, but emoji are much nicer to look at. Some emoji, not
all, have an associated emoticon that can be converted to an emoji character. For example, `:)`
would convert to 🙂.

To enable conversion of an emoticon to a unicode literal character, pass the `convertEmoticon`
option to the matcher.

```tsx
<Interweave
	content="Smiley faces :) ;p :>]"
	matchers={[new EmojiMatcher('emoji', { convertEmoticon: true })]}
/>
```

> A list of supported emoticons can be found in
> [Emojibase](https://github.com/milesj/emojibase/blob/master/packages/generator/src/resources/emoticons.ts).

## Converting shortcodes

Shortcodes provide an easy non-unicode alternative for supporting emoji, and are represented by a
word (or two) surrounded by two colons: `:boy:`.

To enable conversion of a shortcode to a unicode literal character, pass the `convertShortcode`
option to the matcher constructor.

```tsx
<Interweave
	content="Emoji shortcode: :cyclone:"
	matchers={[new EmojiMatcher('emoji', { convertShortcode: true })]}
/>
```

> A list of supported shortcodes can be found in
> [Emojibase](https://github.com/milesj/emojibase/blob/master/packages/generator/src/resources/shortcodes.ts).

## Displaying SVGs or PNGs

To begin, we must enable conversion of unicode characters to media (images, vector, etc), by
enabling the `convertUnicode` option. Secondly, if you want to support shortcodes or emoticons,
enable `convertShortcode` or `convertEmoticon` respectively.

```ts
new EmojiMatcher('emoji', {
	convertEmoticon: true,
	convertShortcode: true,
	convertUnicode: true,
});
```

Now we need to provide an absolute path to the SVG/PNG file using the `emojiPath` prop. This path
must contain a `{{hexcode}}` token, which will be replaced by the hexadecimal codepoint (hexcode) of
the emoji.

Or a function can be passed, which receives the hexcode as the 1st argument, and an object with
`enlarged`, `smallSize`, `largeSize`, and `size` (either depending on enlarge state) properties.

```tsx
<Interweave
  emojiPath="https://example.com/images/emoji/{{hexcode}}.png"
  matchers={[new EmojiMatcher('emoji')]}
/>

// OR

<Interweave
  emojiPath={(hexcode, { size }) => `https://example.com/images/emoji/${size}/${hexcode}.png`}
  matchers={[new EmojiMatcher('emoji')]}
/>
```

Both media formats make use of the `img` tag and will require an individual file, as sprites and
icon fonts are not supported. The following resources can be used for downloading SVG/PNG icons.

- [JoyPixels](http://emojione.com/developers/) (formerly EmojiOne)
- [Twemoji](https://github.com/twitter/twemoji)

> Note: SVGs require CORS to work correctly, so files will need to be stored locally, or within a
> CDN under the same domain. Linking to remote SVGs will not work -- use PNGs instead.

Lastly, to control the width and height of the `img`, use the `emojiSize` prop, which accepts a
number or string. If a number is provided, it'll be passed down to React, which defaults to `px`.

```tsx
<Interweave emojiSize={32} emojiLargeSize={96} /> // 32px, 96px
<Interweave emojiSize="1em" emojiLargeSize="3em" /> // 1em, 3em
```

> I suggest using `em` scaling as the emoji will scale relative to the text around it.

## Displaying unicode characters

To display native unicode characters as is, pass the `renderUnicode` option to the matcher
constructor. This option will override the rendering of SVGs or PNGs, and works quite well alongside
shortcode or emoticon conversion.

```ts
new EmojiMatcher('emoji', { renderUnicode: true });
```

## Automatic enlargement

When an emoji is the only character within the content, it will automatically be enlarged. To
disable this functionality, set `enlargeThreshold` to 0. Inversely, if you want to increase the
threshold in which emojis are enlarged, increase the count.

```ts
new EmojiMatcher('emoji', { enlargeThreshold: 3 });
```

For example, if `enlargeThreshold` is set to 3, and 3 emojis are found, all will be enlarged.

## Testing utilities

Since emoji data must be fetched, this can be rather tedious to mock correctly and efficiently when
testing. To get around this, the `mockEmojiData()` function can be used, which should be called
during your testing framework's boostrap and _not_ in a `beforeEach` event.

By default this will only mock English (`en`) data. If you need to support additional locales, call
the method again with the locale code, but do note that the actual data will still be in English (it
just avoids a fetch).

```ts
import { mockEmojiData } from 'interweave-emoji/test';

mockEmojiData();
mockEmojiData('fr'); // For other locales
```

> Mocking requires the `emojibase-test-utils` dependency to be installed.

[emojibase]: https://emojibase.dev
